home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / applications / misc / pcal-4.5.lha / pcal / ReadMe < prev    next >
Encoding:
Text File  |  1994-10-16  |  15.4 KB  |  359 lines
  1. "Pcal" Version 4.5
  2.  
  3. This is a new release of "Pcal", the PostScript calendar program.  (An
  4. intermediate version, 4.4, was not released publicly.)  
  5.  
  6. Major changes:
  7.  
  8.     1) Of interest to Pcal hackers and installers:
  9.  
  10.       . See various comments below regarding options configurable for your
  11.     site by tweaking various .h files.
  12.  
  13.       . "noprotos.h" has been scrapped; K&R-style function declarations are
  14.     automagically derived from "protos.h" by means of a clever macro,
  15.     thus eliminating the need to keep two .h files in sync.
  16.  
  17.       . Two new files have been added to the distribution: "fonttest_r" and
  18.     "fontmaps_l" (sample calendar files for testing the Roman8 and Latin1
  19.     European language character mappings respectively).  This feature is
  20.     discussed in greater detail below.
  21.       
  22.       . The v4.0 moon phase algorithm has pretty much obviated the need for a
  23.     moon file, but "moon94" and "moon95" have been included nevertheless
  24.     (replacing "moon91" and "moon92").  The moon file message has been
  25.     dropped from the on-line help and from the comments in the sample
  26.     calendar file.  The moon file may now contain "opt -A" and "opt -E"
  27.     lines, thus allowing American-style moon files (those supplied) to be
  28.     used in Europe without modification.
  29.  
  30.       . The Makefiles have been changed: "make clean" leaves pcal intact
  31.     while removing object files and other debris created on the fly;
  32.     "make clobber" removes pcal as well (as "make clean" used to do).
  33.  
  34.       . Selected site-specific defaults (DATEFONT, DATE_STYLE, DOUBLE_SIDED,
  35.     FIRST_DAY, MAPFONTS, NOTESFONT, TIMEZONE, TITLEFONT, SHADING, EPS)
  36.     may now be defined in the Un*x Makefile and its VMS equivalent; see
  37.     Makefile and pcaldefs.h for details.  (Be a part of history - tweak
  38.     the other Makefiles and get your name in the credits for v4.6!)
  39.  
  40.       . The Un*x Makefile has been revised: "make install" now installs
  41.     the executable, raw man page, and packed/compressed man page as
  42.     per current Un*x conventions.  (Thanks to Andrew P. Houghton for
  43.     these modifications.)
  44.  
  45.       . The "help" message is automagically piped through a user-specified
  46.     filter pointed to by environment variable PAGER (default: "more"),
  47.     at least on Un*x systems.  If your non-Un*x system supports/simulates
  48.     pipes via the "popen(3)" interface - or if you'd prefer to use a
  49.     different environment variable or default filter - set/change the
  50.     PAGER_ENV and PAGER_DEFAULT macros in pcaldefs.h.
  51.  
  52.       . The "Generated by..." message confuses some PostScript interpreters
  53.     (e.g., QMS) and has been converted to an EPS-like comment block.
  54.  
  55.       . Additional EPS-isms (page headers and trailers, courtesy of Andrew
  56.     P. Houghton) may be specified by #define'ing EPS as 1 in pcaldefs.h
  57.     or in the Makefile.
  58.  
  59.       .    Pcal now pre-scales all the required fonts/sizes as part of its
  60.     startup code in order to eliminate the overhead of doing so on the
  61.     fly (again, thanks to Andrew P. Houghton for this suggestion).  The
  62.     resulting performance improvement will be most apparent on multi-page
  63.     or whole-year calendars.
  64.  
  65.       . The "pcalinit" program now supports #BEGIN <name> .. #END blocks
  66.     to split the PostScript boilerplate into sub-arrays; writefil.c is
  67.     now smart enought to generate only the PostScript code required
  68.     for any given calendar (e.g., if moons are not requested, the moon
  69.     generation boilerplate will not be generated).  Additionally,
  70.     pcalinit propagates PostScript comments delimited by "%%" to the
  71.     output file (stripping the first '%').
  72.  
  73.       . It has come to my attention that at least one older compiler
  74.     sign-extends the expression (<anychar> & 0377) when promoting it to
  75.     int, resulting in an unwanted negative value.  The masking constant
  76.     0377 has been redefined as CHAR_MSK in pcaldefs.h (and wherever used
  77.     throughout the source) so that it may easily be redefined if
  78.     necessary (see the related comments in pcaldefs.h).
  79.  
  80.       . VMS changes (thanks to Richard Dyson): 1) the old "Makefile.VMS" has
  81.     been been replaced by "Makefile.MMS", which works with either the
  82.     official DEC unbundled product MMS or its public-domain clone MMK;
  83.     2) Make_Pcal.com has been replaced by a simpler version generated
  84.     directly by MMS.
  85.  
  86.  
  87.     2) New command-line options:
  88.  
  89.       . Pcal now supports "-z <timezone>", which adjusts the moon phase
  90.     calculation by <timezone> hours (where <timezone> is expressed in
  91.     hours west of UTC: e.g., Boston = "-z5").  If "-z" is specified -
  92.     with or without a value - Pcal will use its internal algorithm for
  93.     the moon phase calculation even in the presence of a moon file.  The
  94.     default for <timezone> is 0 as shipped, but may be overridden at your
  95.     site by specifying the appropriate value in TIMEZONE (pcaldefs.h).
  96.  
  97.     (Some thought was given to extracting the value from the "TZ"
  98.     environment variable, but that is far from universal even on Un*x,
  99.     let alone the other platforms.  Maybe next time...)
  100.  
  101.       . Pcal generates PostScript code to disable duplex mode (double-sided
  102.     output) on printers which support this.
  103.  
  104.       . Pcal also supports -#<n>, which directs Pcal to print <n> copies of
  105.     each output page.  (Most printer spoolers support this in one form or
  106.     another, but at some sites - including mine [AWR] - multiple copies of
  107.     PostScript files are each preceded by a separate banner page, which
  108.     could be wasteful if you're making, say, 75 copies of your company's
  109.     holiday calendar.)  This may appear in the datefile if '#' is escaped
  110.     by '\' (see below).
  111.  
  112.       . The flags responsible for setting day colors have been expanded and
  113.     revised: -b and -g now accept "holiday" (or "hol") to set the color
  114.     for holidays; -G and -O have been expanded to accept all of the -b
  115.     and -g flags.  (For backward compatibility with v4.3, -G and -O alone
  116.     work more or less as they used to, changing all non-black days to
  117.     outline-gray or outline; cf. change_color() in pcal.c.)  Thus, the
  118.     user can now specify
  119.  
  120.         -O -Ghol
  121.  
  122.     to print weekends as outline, holidays in outline-gray, and (by
  123.     default) other days in black.
  124.  
  125.     The "weekday", "workday", and related keywords now use "logical
  126.     black" - the predominant day color - to define weekdays.  The user
  127.     can thus specify
  128.  
  129.         -Gall -Osat -Osun
  130.  
  131.     and "weekday" will refer to Monday through Friday, even though none
  132.     of the dates are actually printed in black.  Related issue: If not
  133.     explicitly specified otherwise, holidays will print in the least-
  134.     frequently used color of those selected, or in a contrasting color
  135.     if only one color is used; in the above case, holidays will print as
  136.     outlines.
  137.  
  138.     Pcal also accepts ranges of weekdays, which may wrap around the end
  139.     of the week:
  140.  
  141.         -Gfri-sun
  142.  
  143.     prints Friday, Saturday, and Sunday as outline-gray.
  144.  
  145.       .    The "-s" flag now allows the user to specify a set of red/green/blue
  146.     values for the dates and fill boxes.  If a single value is specified,
  147.     it is taken to be a gray scale value (as before); if three colon-
  148.     separated values are specified, they are taken to be red:green:blue
  149.     respectively; for example,
  150.  
  151.         -s1.0:0.0:0.0
  152.  
  153.     directs pcal to print "gray" dates in red.  Outline dates will
  154.     appear in the specified color; "outline-gray" dates will appear
  155.     in the specified color with a black outline.  The fill boxes
  156.     are probably useless in any but the lightest colors, but for
  157.     consistency's sake I decided to support r:g:b values for them
  158.     too.  (Thanks to Denis Girou for the idea and sample code.)
  159.  
  160.       . The "-r" flag has been added.  This flag takes a single argument
  161.     which is the name of a standard 8-bit character set mapping for
  162.     printing the diacritical marks common to European languages; at
  163.     present, this argument may be "roman8" or "latin1" (abbreviated to
  164.     the first character if desired) to specify the Roman8 or ISO Latin1
  165.     mappings respectively.  The default is no mapping; this may be
  166.     overridden by defining MAPFONTS as ROMAN8 or LATIN1 in the Makefile.
  167.     Note that this flag may not be changed on the fly; the final value
  168.     specified will be in effect.
  169.  
  170.     Since the date font is usually used only for printing numbers, it
  171.     is not remapped; if any of the secondary fonts are redefined as
  172.     "datefont", define MAP_DATEFONT as 1 (cf. pcaldefs.h).
  173.  
  174.     New files: "fonttest_r" and "fontmaps_l" are sample calendar files
  175.     for testing the Roman8 and Latin1 character mappings respectively.
  176.  
  177.  
  178.     3) New date file functionality:
  179.  
  180.       . Pcal now handles dates of the form "second Thursday after 12/1".
  181.     Note that the ordinal must be positive; while it could be argued that
  182.     "last Thursday before 12/1" is synonymous with "first Thursday before
  183.     12/1", what does "last Thursday after 12/1 mean?"
  184.  
  185.       . Pcal now supports predefined holidays; at present, it understands
  186.     "Christmas", "Thanksgiving", "Good_Friday", and "Easter" (cf.
  187.     pcallang.h).  So the date file may contain lines like:
  188.  
  189.         Easter*                    Easter Sunday
  190.         Wed before 6th Sun before Easter    Ash Wednesday
  191.         day after Thanksgiving*            holiday
  192.  
  193.     (Algorithms and/or source code to determine the date of other movable
  194.     holidays - e.g., the Jewish calendar, Chinese New Year, solstices,
  195.     etc. - would be welcome!)
  196.  
  197.       . '#' is no longer treated as start-of-comment if escaped by '\'.
  198.  
  199.       . Pcal now accepts two additional European date formats: "dd. mm." and
  200.     and "dd. mon".
  201.  
  202.  
  203.     4) Other new functionality:
  204.  
  205.       . The user may now override the default font size used in printing the
  206.     dates, note text, and month/year title (single-month calendars only);
  207.     for example, "-dCourier/32" sets the date font to 32-point Courier.
  208.     The font and size may be overridden independently: "-[dnt]<font>"
  209.     overrides only the font name, while "-[dnt]/<size>" overrides only
  210.     the size.
  211.  
  212.     The PostScript code responsible for positioning dates, text, etc.
  213.     now does so using actual font sizes, not hard-coded constants.
  214.  
  215.       . Calculating the color in which to print each date has been moved
  216.     from pcalinit.ps to writefil.c, allowing the PostScript code to
  217.     perform a simple array lookup rather than a weekday/holiday
  218.     calculation.
  219.  
  220.       . All of the font size initialization has been moved from pcalinit.ps
  221.     to pcaldefs.h and writefil.c.
  222.  
  223.       . The grid border is drawn using "closepath" to ensure that the lines
  224.     meet properly in the corners (yes, this was visible when using a
  225.     high-resolution printer with repro-grade paper); additionally, the
  226.     grid lines have been increased in width for the small and medium
  227.     calendars (to help ensure uniform line width as physically printed).
  228.  
  229.       . The note box heading and weekday names are now printed in the same
  230.     font as the title and footers; it makes more sense to print all the
  231.     heading text in the same font.  Prefer the old way?  Just change
  232.     WEEKDAYFONT in pcaldefs.h, where the initialization has been moved.
  233.  
  234.       . The font sizes used in printing the medium (whole-year) calendars
  235.     can't be overridden by the user, but they have been enlarged yet
  236.     again for legibility: title = 64, weekdays = 30, dates = 56, footers
  237.     = 14.
  238.  
  239.       . Empty text associated with a date or note entry is propagated to the
  240.     calendar as a blank line; this is useful for grouping related lines
  241.     together.  If you prefer to ignore such lines (as before), define
  242.     KEEP_NULL_LINES (pcaldefs.h) as 0.
  243.  
  244.       . The "help" message is automagically piped through "more" on Un*x
  245.     systems (see section 1 above).
  246.  
  247.       . The "include?" preprocessing directive has been added; if the
  248.     specified file cannot be opened, pcal will silently continue instead
  249.     of terminating with an error.
  250.  
  251.       . The earliest valid year has been moved back from 1900 to 1753 (the
  252.     first full year of the Gregorian calendar in England and her
  253.     colonies).
  254.  
  255.       . The distribution includes "pscalendar", the original shell script/
  256.     PostScript boilerplate (by Patrick Wood, King Ables, and Tim Tessin)
  257.     that would eventually become Pcal.  This is provided primarily as a
  258.     historical curiosity, but it is indeed interesting to reflect on how
  259.     a 300-line shell script eventually turned into over 10,000 lines of
  260.     C and PostScript source.
  261.  
  262.  
  263.     5) Bug fixes:
  264.  
  265.       . Pcal now handles date specifications of the form "Friday nearest
  266.     12/25"; previously, the "nearest" keyword only worked in conjunction
  267.     with wildcard weekdays.  (This fix has been issued previously as a
  268.     patch to v4.3.)
  269.  
  270.       . PostScript routine "holidaytext" has been revised to calculate the
  271.     right margin more accurately, avoiding the occasional overflow into
  272.     the next box.  (In fact, all of the margins have been parameterized,
  273.     as were some hard-coded font sizes in "notetext".)
  274.  
  275.  
  276. Credits:
  277.  
  278. The original calendar PostScript was Copyright (c) 1987 by Patrick Wood and
  279. Pipeline Associates, Inc. with permission to modify and redistribute.
  280.  
  281. The following people contributed to Pcal v4.4 and v4.5:
  282.  
  283.     Overall coordinator:                Joe Brownlee
  284.     VMS support:                    Richard Dyson
  285.     "-z" support:                    Steve Grandi
  286.     Color date support and testing:            Denis Girou
  287.     Un*x makefile revision, EPS assistance and
  288.       testing, font prescaling:            Andrew Houghton
  289.     Internationalization assistance:        Denis Girou (France)
  290.                             Robert Joop (Germany)
  291.     Other C and PostScript code:            Andrew Rogers
  292.  
  293. For a list of all known contributors to date, see the Orig.ReadMe file and
  294. topline comments in pcal.c.
  295.  
  296.  
  297. Andrew W. Rogers
  298. 07 October 1994
  299.  
  300.  
  301. PS: Here's something handy - an alphabetical list of the Pcal options and
  302. their meanings:
  303.  
  304.  
  305. ------------------------------- clip 'n' save -------------------------------
  306.  
  307. -A  parse American date    format        -a  <unused>
  308. -B  don't fill unused boxes        -b  print day in black
  309. -C  define center foot string        -c  generate "calendar"    utility    input
  310. -D  define preprocessor    symbol        -d  select alternate day font
  311. -E  parse European date    format        -e  print empty    calendar
  312. -F  define alternate starting day    -f  select alternate date file
  313. -G  print day as gray-filled outline    -g  print day in gray
  314. -H  <unused>                -h  generate full help message
  315. -I  re-initialize program defaults    -i  <unused>
  316. -J  print Julian day and days left    -j  print Julian day (day of year)
  317. -K  prev in first box, next in last    -k  prev/next in first two boxes
  318. -L  define left    foot string        -l  landscape mode
  319. -M  print all moons            -m  print new/half/full    moons
  320. -N  define heading for notes box    -n  select alternate notes font
  321. -O  print day as empty outline        -o  select alternate output file
  322. -P  <unused>                -p  portrait mode
  323. -Q  <unused>                -q  <unused>
  324. -R  define right foot string        -r  remap fonts for 8-bit characters
  325. -S  suppress small calendars        -s  define date/fill box shading
  326. -T  <unused>                -t  select alternate title font
  327. -U  undefine preprocessor symbol    -u  generate parameter usage message
  328. -V  <unused>                -v  generate version ID
  329. -W  <unused>                -w  print whole    year per page
  330. -X  X-axis transformation        -x  X-axis scale factor
  331. -Y  Y-axis transformation        -y  Y-axis scale factor
  332. -Z  generate debugging information    -z  specify alternate time zone
  333. -#  print multiple copies of each page
  334.  
  335. -----------------------------------------------------------------------------
  336.  
  337.  
  338. PPS: Here's an admittedly-incomplete list of PostScript font names.  All of
  339. these are supported by the printers (Imagen, HP, QMS) that I [AWR] use; your
  340. mileage may vary:
  341.  
  342.     AvantGarde-Book            AvantGarde-BookOblique
  343.     AvantGarde-Demi            AvantGarde-DemiOblique
  344.     Bookman-Demi            Bookman-DemiItalic
  345.     Bookman-Light            Bookman-LightItalic
  346.     Courier                Courier-Bold
  347.     Courier-BoldOblique        Courier-Oblique
  348.     Helvetica            Helvetica-Bold
  349.     Helvetica-BoldOblique        Helvetica-Narrow
  350.     Helvetica-Narrow-Bold        Helvetica-Narrow-BoldOblique
  351.     Helvetica-Narrow-Oblique    Helvetica-Oblique
  352.     NewCenturySchlbk-Bold        NewCenturySchlbk-BoldItalic
  353.     NewCenturySchlbk-Italic        NewCenturySchlbk-Roman
  354.     Palatino-Bold            Palatino-BoldItalic
  355.     Palatino-Italic            Palatino-Roman
  356.     Times-Bold            Times-BoldItalic
  357.     Times-Italic            Times-Roman
  358.     ZapfChancery-MediumItalic
  359.